/**
 * @fileoverview Main CLI object.
 * @author Nicholas C. Zakas
 */

"use strict";

/*
 * The CLI object should *not* call process.exit() directly. It should only return
 * exit codes. This allows other programs to use the CLI object and still control
 * when the program exits.
 */

//------------------------------------------------------------------------------
// Requirements
//------------------------------------------------------------------------------

const fs = require("fs"),
    path = require("path"),
    options = require("./options"),
    CLIEngine = require("./cli-engine"),
    mkdirp = require("mkdirp"),
    log = require("./util/logging");

const debug = require("debug")("eslint:cli");

//------------------------------------------------------------------------------
// Helpers
//------------------------------------------------------------------------------

/**
 * Predicate function for whether or not to apply fixes in quiet mode.
 * If a message is a warning, do not apply a fix.
 * @param {LintResult} lintResult The lint result.
 * @returns {boolean} True if the lint message is an error (and thus should be
 * autofixed), false otherwise.
 */
function quietFixPredicate(lintResult) {
    return lintResult.severity === 2;
}

/**
 * Translates the CLI options into the options expected by the CLIEngine.
 * @param {Object} cliOptions The CLI options to translate.
 * @returns {CLIEngineOptions} The options object for the CLIEngine.
 * @private
 */
// translateOptions 将 CLI 参数转换为引擎能理解的格式
function translateOptions(cliOptions) {
    return {
        envs: cliOptions.env,
        extensions: cliOptions.ext,
        rules: cliOptions.rule,
        plugins: cliOptions.plugin,
        globals: cliOptions.global,
        ignore: cliOptions.ignore,
        ignorePath: cliOptions.ignorePath,
        ignorePattern: cliOptions.ignorePattern,
        configFile: cliOptions.config,
        rulePaths: cliOptions.rulesdir,
        useEslintrc: cliOptions.eslintrc,
        parser: cliOptions.parser,
        parserOptions: cliOptions.parserOptions,
        cache: cliOptions.cache,
        cacheFile: cliOptions.cacheFile,
        cacheLocation: cliOptions.cacheLocation,
        fix: (cliOptions.fix || cliOptions.fixDryRun) && (cliOptions.quiet ? quietFixPredicate : true),
        fixTypes: cliOptions.fixType,
        allowInlineConfig: cliOptions.inlineConfig,
        reportUnusedDisableDirectives: cliOptions.reportUnusedDisableDirectives
    };
}

/**
 * Outputs the results of the linting.
 * @param {CLIEngine} engine The CLIEngine to use.
 * @param {LintResult[]} results The results to print.
 * @param {string} format The name of the formatter to use or the path to the formatter.
 * @param {string} outputFile The path for the output file.
 * @returns {boolean} True if the printing succeeds, false if not.
 * @private
 */
function printResults(engine, results, format, outputFile) {
    let formatter;
    let rules;

    try {
        formatter = engine.getFormatter(format);
        rules = engine.getRules();
    } catch (e) {
        log.error(e.message);
        return false;
    }

    const rulesMeta = {};

    rules.forEach((rule, ruleId) => {
        rulesMeta[ruleId] = rule.meta;
    });

    const output = formatter(results, { rulesMeta });

    if (output) {
        if (outputFile) {
            const filePath = path.resolve(process.cwd(), outputFile);

            if (fs.existsSync(filePath) && fs.statSync(filePath).isDirectory()) {
                log.error("Cannot write to output file path, it is a directory: %s", outputFile);
                return false;
            }

            try {
                mkdirp.sync(path.dirname(filePath));
                fs.writeFileSync(filePath, output);
            } catch (ex) {
                log.error("There was a problem writing the output file:\n%s", ex);
                return false;
            }
        } else {
            log.info(output);
        }
    }

    return true;

}

//------------------------------------------------------------------------------
// Public Interface
//------------------------------------------------------------------------------

/**
 * Encapsulates all CLI behavior for eslint. Makes it easier to test as well as
 * for other Node.js programs to effectively run the CLI.
 */
const cli = {

    /**
     * Executes the CLI based on an array of arguments that is passed in.
     * @param {string|Array|Object} args The arguments to process.
     * @param {string} [text] The text to lint (used for TTY).
     * @returns {int} The exit code for the operation.
     */
    //  ESLint CLI 的核心执行函数，负责处理命令行参数、执行代码检查、输出结果并返回退出码。
    //  `args`: 命令行参数，可以是字符串、数组或对象。
    //  `text`: 可选参数，当从标准输入读取代码时，这里传入要检查的代码字符串。
    execute(args, text) {
        if (Array.isArray(args)) {
            // 如果 `args` 是数组（通常是 `process.argv`），则打印从第三个参数开始的参数（因为前两个是 `node` 和 `eslint` 脚本路径）。
            // 记录调试信息，帮助开发者了解实际传入的参数。
            debug("CLI args: %o", args.slice(2));
        }

        let currentOptions;

        try {
            //  调用 `options.parse` 解析命令行参数，生成 `currentOptions` 对象。
            currentOptions = options.parse(args);
        } catch (error) {
            // 如果解析出错（例如参数不合法），打印错误信息并返回退出码 2（表示配置错误）。
            // 当用户输入无效参数时（如 eslint --invalid-option），会进入 catch 块。
            log.error(error.message);
            return 2;
        }

        // `files`：从解析后的参数中获取文件列表（`currentOptions._` 是未被解析为选项的参数，通常是要检查的文件或目录）。
        // 获取用户指定的文件/目录（如 eslint src/ 中的 src/）
        const files = currentOptions._;

        // `useStdin`：如果传入了 `text` 字符串，则表示使用标准输入（即检查从管道传来的代码）。
        // 判断是否从管道读取内容（如 cat file.js | eslint --stdin）
        const useStdin = typeof text === "string";

        // 当用户运行 eslint --version 时，打印版本号后直接返回。
        if (currentOptions.version) { // version from package.json
            // 如果用户指定了 `--version` 选项，打印当前 ESLint 版本并继续执行
            log.info(`v${require("../package.json").version}`);

        } else if (currentOptions.printConfig) { // `--print-config`：打印指定文件的最终配置（合并了所有配置层）
            // 调试配置问题时使用 eslint --print-config file.js。
            if (files.length) {
                // 必须指定一个文件，
                log.error("The --print-config option must be used with exactly one file name.");
                return 2;
            }
            if (useStdin) {
                // 且不能使用标准输入。
                log.error("The --print-config option is not available for piped-in code.");
                return 2;
            }

            // 创建 `CLIEngine` 实例，获取指定文件的配置，并打印（JSON格式化）。
            const engine = new CLIEngine(translateOptions(currentOptions));

            const fileConfig = engine.getConfigForFile(currentOptions.printConfig);

            log.info(JSON.stringify(fileConfig, null, "  "));
            return 0; // 返回0表示成功。
        } else if (currentOptions.help || (!files.length && !useStdin)) {
            // 如果指定了 `--help` 或者没有指定任何文件且没有标准输入，则打印帮助信息。
            // 用户运行 eslint --help
            log.info(options.generateHelp());

        } else { // 主流程：执行代码检查

            debug(`Running on ${useStdin ? "text" : "files"}`);
             // 参数冲突检查
            if (currentOptions.fix && currentOptions.fixDryRun) {
                //  `--fix` 和 `--fix-dry-run` 不能同时使用（一个是实际修复，一个是模拟修复）。
                log.error("The --fix option and the --fix-dry-run option cannot be used together.");
                return 2;
            }

            if (useStdin && currentOptions.fix) {
                // 标准输入模式下不能使用 `--fix`（因为修复需要写文件，而标准输入没有文件路径），只能使用 `--fix-dry-run`。
                log.error("The --fix option is not available for piped-in code; use --fix-dry-run instead.");
                return 2;
            }

            if (currentOptions.fixType && !currentOptions.fix && !currentOptions.fixDryRun) {
                // `--fix-type` 必须和 `--fix` 或 `--fix-dry-run` 一起使用（它指定修复类型，如问题、布局等）。
                log.error("The --fix-type option requires either --fix or --fix-dry-run.");
                return 2;
            }

            //  创建 CLIEngine 并执行检查,将命令行参数转换为 `CLIEngine` 的选项（`translateOptions` 函数）。
            const engine = new CLIEngine(translateOptions(currentOptions));
            // 使用标准输入：调用 `executeOnText` 检查传入的字符串（`text`）。`currentOptions.stdinFilename` 是模拟的文件名（如果提供了 `--stdin-filename`）。
            // 使用文件：调用 `executeOnFiles` 检查文件列表。
            const report = useStdin ? engine.executeOnText(text, currentOptions.stdinFilename, true) : engine.executeOnFiles(files);

            // 当用户使用 --fix 参数时，自动修改文件。
            if (currentOptions.fix) {
                // 如果指定了 `--fix`，则调用 `CLIEngine.outputFixes(report)` 将修复写入文件。
                debug("Fix mode enabled - applying fixes");
                CLIEngine.outputFixes(report);
            }

            // 使用 --quiet 参数时，过滤掉所有警告，只显示错误。
            if (currentOptions.quiet) {
                // 如果指定了 `--quiet`，则过滤掉警告，只保留错误。
                debug("Quiet mode enabled - filtering out warnings");
                report.results = CLIEngine.getErrorResults(report.results);
            }

            //  调用 `printResults` 函数输出检查结果（可以输出到文件或控制台）。如果输出成功，则继续处理，否则返回2（表示输出错误）。
            if (printResults(engine, report.results, currentOptions.format, currentOptions.outputFile)) {
                // 计算警告是否超过阈值（`--max-warnings` 选项）：如果设置了最大警告数（>=0）且实际警告数超过，则标记 `tooManyWarnings`。
                const tooManyWarnings = currentOptions.maxWarnings >= 0 && report.warningCount > currentOptions.maxWarnings;

                if (!report.errorCount && tooManyWarnings) {
                    // 如果没有错误，但警告超限，打印错误信息。
                    log.error("ESLint found too many warnings (maximum: %s).", currentOptions.maxWarnings);
                }

                // 如果有错误或警告超限，返回1（表示检查未通过）。否则返回0（成功）。
                return (report.errorCount || tooManyWarnings) ? 1 : 0;
            }

            // 如果 `printResults` 失败（返回false），则返回2。
            return 2;


        }
        //  对于版本查询、帮助等特殊情况，最后返回0（成功）。
        return 0;
    }
};

module.exports = cli;
